%%::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
%%
%%    This file is part of ICTP RegCM.
%%    
%%    Use of this source code is governed by an MIT-style license that can
%%    be found in the LICENSE file or at
%%
%%         https://opensource.org/licenses/MIT.
%%
%%    ICTP RegCM is distributed in the hope that it will be useful,
%%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
%%
%%::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

We will review here a sample installation session of software needed to
install the RegCM model.

The starting point is here a Linux system on a multicore processor box, and
the final goal is to have an optimized system to run the model.
I will use \verb=bash= as my shell and assume that GNU development tools like
\verb=make=, \verb=sed=, \verb=awk= are installed as part of the default
Operating System environment as is the case in most Linux distro.
I will require also for commodity a command line web downloader such as
\verb=curl= installed on the system, along its development libraries to be
used to enable OpenDAP remote data access protocol capabilities of netCDF
library. Standard file management tools such as \verb=tar= and \verb=gzip=
and \verb=wget= are also required.
The symbol \verb=$>= will stand for a shell prompt.
I will assume that the process is performed as a normal system user, which
will own all the toolchain. I will be now just the \verb=regcm= user.

\section{Identify Processor}

First step is to identify the processor to know its capabilities:

\begin{Verbatim}
$> cat /proc/cpuinfo
\end{Verbatim}

This command will ask to the operating system to print processor informations.
A sample answer on my laptop is:

\begin{Verbatim}
processor       : 0
vendor_id       : GenuineIntel
cpu family      : 6
model           : 30
model name      : Intel(R) Core(TM) i7 CPU       Q 740  @ 1.73GHz
stepping        : 5
cpu MHz         : 933.000
cache size      : 6144 KB
physical id     : 0
siblings        : 8
core id         : 0
cpu cores       : 4
apicid          : 0
initial apicid  : 0
fpu             : yes
fpu_exception   : yes
cpuid level     : 11
wp              : yes
flags           : fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge
mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe syscall
nx rdtscp lm constant_tsc arch_perfmon pebs bts rep_good nopl xtopology
nonstop_tsc aperfmperf pni dtes64 monitor ds_cpl vmx smx est tm2 ssse3
cx16 xtpr pdcm sse4_1 sse4_2 popcnt lahf_lm ida dts tpr_shadow vnmi
flexpriority ept vpid
bogomips        : 3467.81                                                       
clflush size    : 64                                                            
cache_alignment : 64                                                            
address sizes   : 36 bits physical, 48 bits virtual                             
power management:
\end{Verbatim}

repeated eight time with Processor Ids from 0 to 7: I have a Quad Core Intel
with Hyperthreading on (this multiply by 2 the reported processor list).
The processor reports here also to support Intel Streaming SIMD Extensions V4.2,
which can be later used to speed up code execution vectorizing floating point
operation on any single CPU core.

\section{Chose compiler}

Depending on the processor, we can chose which compiler to use. On a Linux box,
we have multiple choices:

\begin{itemize}
\item GNU Gfortran
\item G95
\item Intel ifort compiler
\item Portland compiler
\item Absoft ProFortran
\item NAG Fortran Compiler
\end{itemize}

and for sure other which I may not be aware of. All of these compilers have pros
and cons, so I am just for now selecting one in the pool only to continue the
exposition.

With some modification (the path, the script, the arguments to the script),
same step is to be performed for all non-GNU compilers in the above list, and
is documented in the installation manual of the compiler itself.

In case of GNU, to check the correct behaviour of the compiler, try to
type the following command:

\begin{Verbatim}
$> gfortran --version
GNU Fortran (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

\end{Verbatim}

\section{Environment setup}

We will now use the \verb=prereq_install= shell script provided in the
\verb=Tools/Scripts= directory. Given the above environment, we can edit
the file and decomment the lines relative to the selected compiler.

\begin{Verbatim}
# Working CC Compiler
CC=gcc
#CC=icc
#CC=pgcc
# Working C++ Compiler
CXX=g++
#CXX=icpc
#CXX=pgCC
# Working Fortran Compiler
FC=gfortran
#FC=ifort
#FC=pgf90
# Destination directory
DEST=/home/regcm
\end{Verbatim}

I am now ready to compile software.

\section{Pre requisite library installation}

The help script will build netCDF V4 and MPI libraries to be used to
compile the RegCM model.

Then we can just execute the script:

\begin{Verbatim}
$> ./prereq_install.sh
This script installs the netCDF/mpi librares in the

         /home/regcm

directory. If something goes wrong, logs are saved in

         /home/regcm/logs

Downloading ZLIB library...
Downloading HDF5 library...
Downloading netCDF Library...
Downloading MPICH2 Library...
Compiling MPI library.
Compiled MPI library.
Compiling zlib Library.
Compiled zlib library.
Compiling HDF5 library.
Compiled HDF5 library.
Compiling netCDF Library.
Compiled netCDF C library.
Compiled netCDF Fortran library.
Done!
To link RegCM with this librares use:

PATH=/home/regcm/bin:$PATH ./configure \
  CC=gcc FC=gfortran \
  CPPFLAGS=-I/home/regcm/include \
  LDFLAGS=-L/home/regcm/lib \
  LIBS="-lnetcdff -lnetcdf -lhdf5_hl -lhdf5 -lz"

\end{Verbatim}

The admins who must compile the pre requisite libraries are invited to look
at the script, identifying the various steps.
The normal user should be content of the last printout message which details
how to use the just built libraries to compile RegCM model sources against.
At run time an environment variable must be added to set correct paths:

\begin{Verbatim}
$> export PATH=/home/regcm/bin:$PATH
\end{Verbatim}

The above is needed to be repeated for any shell which is used to run
RegCM programs, and can be appended for convenience on the user shell
startup scripts.
